// GameAction.java
package org.zjx.core;

import org.zjx.exception.ActionValidationException;
import java.util.Map;

/**
 * 游戏动作接口 - 定义游戏中的基本动作行为
 *
 * 这个接口是所有游戏动作的基础契约，定义了获取动作ID、参数以及验证动作有效性的方法。
 * 实现类需要提供具体的动作逻辑和验证规则。
 */
public interface GameAction {
    /**
     * 获取动作唯一ID
     *
     * @return 动作的唯一标识符字符串，用于区分不同的游戏动作
     */
    String getActionId();


    void execute();

    /**
     * 获取动作参数
     *
     * @return 包含动作所有参数的键值对映射，参数类型和含义由具体动作决定
     */
    Map<String, Object> getParams();

    /**
     * 验证动作有效性
     *
     * 检查动作是否满足执行条件，如参数是否合法、游戏状态是否允许等。
     *
     * @throws ActionValidationException 当动作验证失败时抛出，包含错误代码和详细信息
     */
    void validate() throws ActionValidationException;
}